SparkN0de-git - /page/commit.mu

Micron Document

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

| SparkN0de-git | SparkN0de |

Node / ReticulumProjects / MeshChatX.git / commits / e234e0e

Commit e234e0eb4d153c85a3dbb4a3ee0eb6b480ae9373

󰉖 Browse tree at this commit

Parents : 839e106

Author : Sudo-Ivan <ivan@quad4.io>

Signature : Signature validation error

Date : 2026-03-06T02:35:51-06:00

Update README.md

Changes

1 files changed, 167 insertions(+), 224 deletions(-)

M README.md +167 -224

Diff

diff --git a/README.md b/README.md

index 4339bb67..bcc85d25 100644

--- a/README.md

+++ b/README.md

@@ -1,313 +1,256 @@

# Reticulum MeshChatX

-[Todo](https://todo.quad4.io/1/public/boards/QMC3b2ztD4FAWr7GaErN9HQY) - Website (Soon)

+A extensively modified and feature-rich fork of Reticulum MeshChat by Liam Cottle.

-> [!WARNING]

-> Backup your reticulum-meshchat folder before using! MeshChatX will attempt to auto-migrate whatever it can from the old database without breaking things, but it is best to keep backups.

+This project is independent from the original Reticulum MeshChat project and is not affiliated with it.

-Contact me for any issues or ideas:

+- Source: [git.quad4.io/RNS-Things/MeshChatX](https://git.quad4.io/RNS-Things/MeshChatX)

+- Releases: [git.quad4.io/RNS-Things/MeshChatX/releases](https://git.quad4.io/RNS-Things/MeshChatX/releases)

+- Changelog: [`CHANGELOG.md`](CHANGELOG.md)

-```

-LXMF: 7cc8d66b4f6a0e0e49d34af7f6077b5a

-```

+## Important Notes

+- Full LXMF support is a core project focus.

+- Storage and migration work has been progressively reworked toward raw SQL (replacing legacy Peewee ORM paths where applicable).

+> [!WARNING]

+> MeshChatX is not guaranteed to be wire/data compatible with older Reticulum MeshChat releases. Back up data before migration/testing.

-[![CI](https://git.quad4.io/RNS-Things/MeshChatX/actions/workflows/ci.yml/badge.svg?branch=master)](https://git.quad4.io/RNS-Things/MeshChatX/actions/workflows/ci.yml)

-[![Tests](https://git.quad4.io/RNS-Things/MeshChatX/actions/workflows/tests.yml/badge.svg?branch=master)](https://git.quad4.io/RNS-Things/MeshChatX/actions/workflows/tests.yml)

-[![Build](https://git.quad4.io/RNS-Things/MeshChatX/actions/workflows/build.yml/badge.svg?branch=master)](https://git.quad4.io/RNS-Things/MeshChatX/actions/workflows/build.yml)

-[![Docker](https://git.quad4.io/RNS-Things/MeshChatX/actions/workflows/docker.yml/badge.svg?branch=master)](https://git.quad4.io/RNS-Things/MeshChatX/actions/workflows/docker.yml)

+> [!WARNING]

+> Legacy systems are not fully supported yet. Current baseline is Python `>=3.11` and Node `>=24`.

-A [Reticulum MeshChat](https://github.com/liamcottle/reticulum-meshchat) fork from the future.

+## Demo And Screenshots

-This project is separate from the original Reticulum MeshChat project, and is not affiliated with the original project.

+### UI Previews

-## Goal

+![Phone](screenshots/phone.png)

+![Network Visualiser](screenshots/network-visualiser.png)

+![Archives](screenshots/archives.png)

+![Identities](screenshots/identities.png)

-To provide everything you need for Reticulum, LXMF, and LXST in one beautiful and feature-rich application.

+## Requirements

-- Desktop app (Linux, Windows, macOS)

-- Self-host on your server easily with or without containers

-- Mobile support (Android)

-- Reliable, secure, fast and easy to use.

+- Python `>=3.11` (from `pyproject.toml`)

+- Node.js `>=24` (from `package.json`)

+- pnpm `10.30.0` (from `package.json`)

+- Poetry (used by `Taskfile.yml` and CI workflows)

-Note on macOS: You will need to manually build or use containers since I do not have a macOS machine or runner.

+## Nix (flake.nix)

-## Quick Start (Docker - Recommended)

+This repo includes a Nix flake at `flake.nix`.

-The easiest way to get MeshChatX running is using Docker. Our official image is multi-arch and supports `linux/amd64` and `linux/arm64` (Raspberry Pi, etc.).

+### Enter the dev shell

```bash

-# Pull and run the latest image

-docker pull git.quad4.io/rns-things/meshchatx:latest

-# Run MeshChatX using Docker Compose (Recommended)

-# This will create a meshchat-config directory for persistence

-docker compose up -d

+nix develop

```

-### Docker Permissions Note

+The flake dev shell provides Python, Poetry, Node, pnpm, Task, packaging tools (`rpm`, `dpkg`, `fakeroot`), Android build tools, and Docker tooling.

-If you encounter a `PermissionError` when running the Docker container, it's likely because the container's user (UID 1000) doesn't have permission to write to your host's `./meshchat-config` folder. You can fix this by running:

+### Build the default Nix package

```bash

-sudo chown -R 1000:1000 ./meshchat-config

+nix build .#default

```

-Check [releases](https://git.quad4.io/RNS-Things/MeshChatX/releases) for pre-built binaries (AppImage, DEB, EXE) if you prefer standalone apps. (coming soon)

-### Installation via Wheel (.whl)

-The simplest way to install MeshChatX on most systems is using the pre-built wheel from our releases. This package **bundles the built frontend**, so you don't need to deal with Node.js or building assets yourself. No Electron needed, it is a webserver basically, so you use your browser to access it.

-1. **Install directly from the release**:

- ```bash

- pip install https://git.quad4.io/RNS-Things/MeshChatX/releases/download/v4.1.0/reticulum_meshchatx-4.1.0-py3-none-any.whl

- # pipx

- pipx install https://git.quad4.io/RNS-Things/MeshChatX/releases/download/v4.1.0/reticulum_meshchatx-4.1.0-py3-none-any.whl

- ```

+### Typical workflow inside `nix develop`

-2. **Run MeshChatX**:

- ```bash

- meshchat --headless

- ```

-## Major Features

-- **Full LXST Support**: Custom voicemail, phonebook, contact sharing, and ringtone support.

-- **Interface Discovery and auto-connecting** - Discover interfaces, auto-connect or connect to trusted ones, map them all!

-- **Multi-Identity**: Switch between multiple Reticulum identities seamlessly.

-- **Modern UI/UX**: A completely redesigned, intuitive interface.

-- **Integrated Maps**: OpenLayers with MBTiles support for offline maps.

-- **Security**: Read more about it in the [Security](#security) section.

-- **Offline Docs**: Access Reticulum documentation without an internet connection.

-- **Expanded Tools**: Includes dozens of more tools.

-- **Page Archiving**: Built-in crawler and browser for archived pages offline.

-- **Banishment**: Banish LXMF users, Telephony, and NomadNet Nodes.

-- **i18n**: Support for English, German, Italian, and Russian.

-- **Advanced Diagnostic Engine**: Mathematically grounded crash recovery using Active Inference and Information Theory.

-## Screenshots

-<details>

-<summary>Telephony & Calling</summary>

-### Phone

-![Phone](screenshots/phone.png)

-### Active Call

-![Calling](screenshots/calling.png)

-### Call Ended

+```bash

+task install

+task lint:all

+task test:all

+task build:all

+```

-![Call Ended](screenshots/calling-end.png)

+## Install Methods

-### Voicemail

+Use the method that matches your environment and packaging preference.

-![Voicemail](screenshots/voicemail.png)

+| --- | --- | --- | --- |

-### Ringtone Settings

+Notes:

-![Ringtone](screenshots/ringtone.png)

+- The release workflow explicitly builds Linux `x64` and `arm64` AppImage + DEB.

+- RPM is also attempted by release workflow and uploaded when produced.

-</details>

+## Quick Start: Docker

-<details>

-<summary>Networking & Visualization</summary>

+```bash

+docker compose up -d

+```

-### Network Visualiser

+Default compose file maps:

-![Network Visualiser](screenshots/network-visualiser.png)

-![Network Visualiser 2](screenshots/network-visualiser2.png)

+- `127.0.0.1:8000` on host -> container port `8000`

+- `./meshchat-config` -> `/config` for persistence

-</details>

+If your local `meshchat-config` permissions block writes, fix ownership:

-<details>

-<summary>Page Archives</summary>

+```bash

+sudo chown -R 1000:1000 ./meshchat-config

+```

-### Archives Browser

+## Install from Release Artifacts

-![Archives](screenshots/archives.png)

+### 1) Linux AppImage (x64/arm64)

-### Viewing Archived Page

+1. Download `ReticulumMeshChatX-v<version>-linux-<arch>.AppImage` from releases.

+2. Make it executable and run:

-![Archive View](screenshots/archive-view.png)

+```bash

+chmod +x ./ReticulumMeshChatX-v*-linux-*.AppImage

+./ReticulumMeshChatX-v*-linux-*.AppImage

+```

-</details>

+### 2) Debian/Ubuntu `.deb` (x64/arm64)

-<details>

-<summary>Tools & Identities</summary>

+1. Download `ReticulumMeshChatX-v<version>-linux-<arch>.deb`.

+2. Install:

-### Tools

+```bash

+sudo apt install ./ReticulumMeshChatX-v*-linux-*.deb

+```

-![Tools](screenshots/tools.png)

+### 3) RPM-based systems

-### Identity Management

+1. Download `ReticulumMeshChatX-v<version>-linux-<arch>.rpm` if present in the release.

+2. Install with your distro tool:

-![Identities](screenshots/identities.png)

+```bash

+sudo rpm -Uvh ./ReticulumMeshChatX-v*-linux-*.rpm

+```

-</details>

+### 4) Python wheel (`.whl`)

-### Pipx / Global Installation

+Release wheels include the built web assets.

-If you prefer to install MeshChatX globally using `pipx, pip or uv`, you can do so directly from the repository. However, you must specify the path to your built frontend files using the `--public-dir` flag or `MESHCHAT_PUBLIC_DIR` environment variable, as the static files are not bundled with the source code. The release .whl packages include the built frontend files and also there is a seperate frontend zip to grab and use.

+```bash

+pip install ./reticulum_meshchatx-*-py3-none-any.whl

+meshchat --headless

+```

-1. **Install MeshChatX**:

+`pipx` is also supported:

- ```bash

- pipx install git+https://git.quad4.io/RNS-Things/MeshChatX

- ```

+```bash

+pipx install ./reticulum_meshchatx-*-py3-none-any.whl

+```

-2. **Run with Frontend Path**:

- ```bash

- # Replace /path/to/MeshChatX/meshchatx/public with your actual path

- meshchat --public-dir /path/to/MeshChatX/meshchatx/public

- ```

+## Run from Source (Web Server Mode)

-### Manual Installation (From Source)

+Use this when developing or when you need a local custom build.

-If you want to run MeshChatX from the source code locally:

+```bash

+git clone https://git.quad4.io/RNS-Things/MeshChatX.git

+cd MeshChatX

+corepack enable

+pnpm install

+pip install poetry

+poetry install

+pnpm run build-frontend

+poetry run meshchat --headless --host 127.0.0.1

+```

-1. **Clone the repository**:

+## Build Desktop Packages from Source

- ```bash

- git clone https://git.quad4.io/RNS-Things/MeshChatX

- cd MeshChatX

- ```

+These scripts are defined in `package.json` and `Taskfile.yml`.

-2. **Build the Frontend**:

- Requires Node.js and pnpm.

+### Linux x64 AppImage + DEB

- ```bash

- corepack enable

- pnpm install

- pnpm run build-frontend

- ```

+```bash

+pnpm run dist:linux-x64

+```

-3. **Install & Run Backend**:

- Requires Python 3.10+ and Poetry.

- ```bash

- pip install poetry

- poetry install

- poetry run meshchat --headless --host 127.0.0.1

- ```

+### Linux arm64 AppImage + DEB

-### Cross-Platform Building (Linux to Windows)

+```bash

+pnpm run dist:linux-arm64

+```

-If you are on Linux and want to build the Windows `.exe` and installer locally, you can use **Wine**.

+### RPM

-1. **Install Windows Python and Git inside Wine**:

+```bash

+pnpm run dist:rpm

+```

- ```bash

- # Download Python installer

- wget https://www.python.org/ftp/python/3.13.1/python-3.13.1-amd64.exe

- # Install Python to a specific path

- wine python-3.13.1-amd64.exe /quiet InstallAllUsers=1 TargetDir=C:\Python313 PrependPath=1

+Or through Task:

- # Download Git installer

- wget https://github.com/git-for-windows/git/releases/download/v2.52.0.windows.1/Git-2.52.0-64-bit.exe

- # Install Git (quietly)

- wine Git-2.52.0-64-bit.exe /VERYSILENT /NORESTART

- ```

+```bash

+task dist:fe:rpm

+```

-2. **Install Build Dependencies in Wine**:

+## Architecture Support Summary

- ```bash

- wine C:/Python313/python.exe -m pip install cx_Freeze poetry

- wine C:/Python313/python.exe -m pip install -r requirements.txt

- ```

+- Docker image: `amd64`, `arm64`

+- Linux AppImage: `x64`, `arm64`

+- Linux DEB: `x64`, `arm64`

+- Windows: `x64`, `arm64` (build scripts available)

+- macOS: build scripts available (`arm64`, `universal`) for local build environments

+- Android: build workflow and Android project are present in this repository

-3. **Run the Build Task**:

+## Android

- ```bash

- # Build only the Windows portable exe

- WINE_PYTHON="wine C:/Python313/python.exe" task dist:win:wine

+Use the dedicated docs:

- # Or build everything (Linux + Windows) at once

- WINE_PYTHON="wine C:/Python313/python.exe" task dist:all:wine

- ```

+- [`docs/meshchatx_on_android_with_termux.md`](docs/meshchatx_on_android_with_termux.md)

+- [`android/README.md`](android/README.md)

## Configuration

-MeshChatX can be configured via command-line arguments or environment variables.

+MeshChatX supports both CLI args and env vars.

-| :-------------- | :--------------------- | :---------- | :------------------- |

+| --- | --- | --- | --- |

## Development

-We use [Task](https://taskfile.dev/) for automation.

-| Task | Description |

-| :------------------------- | :--------------------------------------------- |

-| `task install` | Install all dependencies |

-| `task run` | Run the application |

-| `task dev` | Run the application in development mode |

-| `task lint:all` | Run all linters (Python & Frontend) |

-| `task lint:be` | Lint Python code only |

-| `task lint:fe` | Lint frontend code only |

-| `task fmt:all` | Format all code (Python & Frontend) |

-| `task fmt:be` | Format Python code only |

-| `task fmt:fe` | Format frontend code only |

-| `task test:all` | Run all tests |

-| `task test:cov` | Run tests with coverage reports |

-| `task test:be` | Run Python tests only |

-| `task test:fe` | Run frontend tests only |

-| `task build:all` | Build frontend and backend |

-| `task build:fe` | Build only the frontend |

-| `task build:wheel` | Build Python wheel package |

-| `task compile` | Compile Python code to check for syntax errors |

-| `task docker:build` | Build Docker image using buildx |

-| `task docker:run` | Run Docker container using docker-compose |

-| `task dist:linux:appimage` | Build Linux AppImage |

-| `task dist:win:exe` | Build Windows portable executable |

-| `task dist:win:wine` | Build Windows portable (Wine cross-build) |

-| `task dist:all` | Build all Electron apps |

-| `task dist:all:wine` | Build all Electron apps (Wine cross-build) |

-| `task android:prepare` | Prepare Android build |

-| `task android:build` | Build Android APK |

-| `task dist:fe:flatpak` | Build Flatpak package |

-| `task clean` | Clean build artifacts and dependencies |

+Common tasks from `Taskfile.yml`:

-## Security

+```bash

+task install

+task lint:all

+task test:all

+task build:all

+```

-- [ASAR Integrity](https://www.electronjs.org/docs/latest/tutorial/asar-integrity) (Stable as of Electron 39)

-- Built-in automatic integrity checks on all files (frontend and backend)

-- HTTPS by default (automated locally generated certs)

+## Versioning

-* **Layered CSP Protection**: 3-layer Content Security Policy (Backend, Electron Session, and Loading Screen) to prevent XSS and unauthorized resource loading.

+Current version in this repo is `4.2.1`.

-- Redundant CORS protection (loading.html, python backend server, electron main.js)

-- Updated dependencies and daily scanning (OSV)

-- **Comprehensive Scanning Pipeline**: Integrated [Trivy](https://github.com/aquasecurity/trivy) for filesystem and container image scanning, alongside [OSV-Scanner](https://github.com/google/osv-scanner) for vulnerability tracking.

-- SBOM for dependency observability and tracking

-- Extensive testing and fuzzing (Property-based testing with Hypothesis).

-- Rootless docker images

-- Pinned actions and container images (supply chain security and deterministic builds)

+- `package.json` is the JavaScript/Electron version source.

+- `meshchatx/src/version.py` is synced from `package.json` using:

-## Advanced Diagnostic Engine

+```bash

+pnpm run version:sync

+```

-MeshChatX includes a uniquely sophisticated crash recovery system designed for the unpredictable hardware environments.

+For release consistency, keep version fields aligned where required (`package.json`, `pyproject.toml`, `meshchatx/__init__.py`).

+## Security

-- **Probabilistic Active Inference**: Uses Bayesian-inspired heuristics to determine root causes (e.g., OOM, RNS config issues, LXMF storage failures) with up to 99% confidence.

-- **Mathematical Grounding**: Quantifies system instability using Shannon Entropy and KL-Divergence, providing a numerical "disorder index" at the time of failure.

-- **Manifold Mapping**: Identifies "Failure Manifolds" across the entire vertical stack from Kernel and Python versions to RNS interface state and LXMF database integrity.

+Security and integrity details:

-All running locally on your own hardware and it might not be perfect, but it will only get better. The idea is to provide you the help to possibly fix it when you cannot reach me.

+- [`SECURITY.md`](SECURITY.md)

+- Built-in integrity checks and HTTPS/WSS defaults in app runtime

+- CI scanning workflows in `.gitea/workflows/`

## Credits

- [Liam Cottle](https://github.com/liamcottle) - Original Reticulum MeshChat

-- [RFnexus](https://github.com/RFnexus) - [micron-parser-js](https://github.com/RFnexus/micron-parser-js)

-- [Marqvist](https://github.com/markqvist) - Reticulum, LXMF, LXST

+- [RFnexus](https://github.com/RFnexus) - micron parser JavaScript work

+- [markqvist](https://github.com/markqvist) - Reticulum, LXMF, LXST

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────